{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "48c92d94-f7f0-4d07-b96b-4eeae31df55f",
   "metadata": {},
   "source": [
    "# Legend Options\n",
    "\n",
    "```{eval-rst}\n",
    ".. plotting-options-table:: Legend Options\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7c6cc816-2cc3-4af6-94a5-ed04b3bfe3ce",
   "metadata": {},
   "source": [
    "(option-legend)=\n",
    "## `legend`\n",
    "\n",
    "Controls whether and where the legend appears.  \n",
    "- Set `legend=False` to hide the legend.  \n",
    "- Use `legend=True` (or `legend='right'`) to show it in the default position.  \n",
    "- Specify one of the cardinal positions `'top'`, `'bottom'`, `'left'`, or `'right'`.  \n",
    "- Choose a corner placement with `'top_left'`, `'top_right'`, `'bottom_left'`, or `'bottom_right'`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6d07e0f0-8cde-4e2f-9ab9-47dc06be11b6",
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.penguins(\"pandas\")\n",
    "\n",
    "opts = dict(\n",
    "    x='flipper_length_mm', y='body_mass_g', by='species',\n",
    "    frame_width=200, aspect='square'\n",
    ")\n",
    "plot1 = df.hvplot.scatter(title=\"Default: legend=right\", **opts)\n",
    "plot2 = df.hvplot.scatter(legend='left', title=\"legend=left\", **opts)\n",
    "plot3 = df.hvplot.scatter(legend='top', title=\"legend=top\", **opts)\n",
    "plot4 = df.hvplot.scatter(legend='bottom', title=\"legend=bottom\", **opts)\n",
    "plot5 = df.hvplot.scatter(legend='bottom_left', title=\"legend=bottom_left\", **opts)\n",
    "plot6 = df.hvplot.scatter(legend='bottom_right', title=\"legend=bottom_right\", **opts)\n",
    "plot7 = df.hvplot.scatter(legend='top_left', title=\"legend=top_left\", **opts)\n",
    "plot8 = df.hvplot.scatter(legend='top_right', title=\"legend=top_right\", **opts)\n",
    "plot1 + plot2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "48367226-cce5-4675-9408-f4ca2f586236",
   "metadata": {},
   "outputs": [],
   "source": [
    "plot3 + plot4"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "964954e3-acc4-419c-96af-5e9409c7d2f2",
   "metadata": {},
   "outputs": [],
   "source": [
    "plot5 + plot6"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "baa84773-9626-43a1-b981-e7c81614d1c5",
   "metadata": {},
   "outputs": [],
   "source": [
    "plot7 + plot8"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e7f37498-781a-422b-9338-1b8d7d536076",
   "metadata": {},
   "source": [
    "(option-legend_cols)=\n",
    "## `legend_cols`\n",
    "\n",
    "The `legend_cols` option allows to define the number of columns of the legend grid."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c1e9c1dd-16fb-4685-b0be-619ce21227cd",
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "import numpy as np\n",
    "import pandas as pd\n",
    "\n",
    "df = pd.DataFrame({\"y\": np.random.random(20), \"cat\": list(map(chr, range(97, 117)))})\n",
    "\n",
    "df.hvplot.scatter(by=\"cat\", height=250, legend_cols=3, title=\"legend_cols=3\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "80cc2580-8c29-4fab-8947-8d3f3f937373",
   "metadata": {},
   "source": [
    "(option-legend_opts)=\n",
    "## `legend_opts`\n",
    "\n",
    "The `legend_opts` option allows to customize the legend styling. For the Bokeh plotting backend, the dictionary keys should be properties of its [`Legend` model](https://docs.bokeh.org/en/latest/docs/reference/models/annotations.html#bokeh.models.Legend), such as `background_fill_alpha`, `background_fill_color`, etc."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0dafe596-72d3-4b6f-8484-ee3621bfb063",
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.penguins(\"pandas\")\n",
    "\n",
    "df.hvplot.scatter(\n",
    "    x=\"bill_length_mm\", y=\"bill_depth_mm\", by=\"species\",\n",
    "    legend_opts={\"background_fill_alpha\": 0.2, \"background_fill_color\": \"grey\", \"spacing\": 20}\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4f2d87e8-8821-42d7-a71f-bb5daeaf0aed",
   "metadata": {},
   "source": [
    "For the Matplotlib plotting backend, the keys should be keyword arguments of its [`Axes.legend` method](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.legend.html), such as `framealpha`, `facecolor`, etc."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "739b34ee-ebf2-4acc-9a9b-3e659b1c6a74",
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "hvplot.extension(\"matplotlib\")\n",
    "\n",
    "df = hvplot.sampledata.penguins(\"pandas\")\n",
    "\n",
    "df.hvplot.scatter(\n",
    "    x=\"bill_length_mm\", y=\"bill_depth_mm\", by=\"species\",\n",
    "    legend_opts={\"framealpha\": 0.2, \"facecolor\": \"grey\", \"labelspacing\": 2}\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6296c0ce-f273-402e-8ff5-110b2d6c0a40",
   "metadata": {},
   "source": [
    ":::{seealso}\n",
    "The [`backend_opts`](option-backend_opts) option to customize even more the styling of a plot.\n",
    ":::"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
